IconSuiteToRgn

IconSuiteToRgn
Header:	Icons.h		Carbon status:	Supported

Converts the icon mask in an icon suite to a region.

OSErr IconSuiteToRgn (
     theRgn, 
    const Rect *iconRect, 
    IconAlignmentType align, 
    IconSuiteRef theIconSuite
);

theRgn

On return, a handle to the requested region. You must allocate memory for the region handle before calling this function.

The returned region corresponds to the icon’s mask (the mask defined by either an 'ICN#' or 'ics#' entry in an icon suite, according to the rectangle and alignment specified in the iconRect and align parameters).

Once you have a region that describes the icon mask for a given icon, you can use it to perform accurate hit-testing and outline dragging of the icon in your application.

iconRect

A pointer to the rectangle in which the icon is to be drawn, specified in local coordinates of the current graphics port. The function uses this rectangle as the bounding box of the region. The function determines, from the size of the rectangle specified here, which icon mask to use from the icon suite.

align

Specifies how the function should align the region within the rectangle. See “Alignment Type Values” for a description of the values you can use in this parameter.

theIconSuite

A handle to an icon suite.

function result: A result code.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. For that reason, your application should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.